<html>
<head>
<title>User Manual: UI</title>
<link href="./page.css" rel="stylesheet" type="text/css"/>
<link href="./olive.css" rel="stylesheet" type="text/css"/>
<link href="./manual.css" rel="stylesheet" type="text/css"/>
</head>
<body>

<h1>2. The Olive User Interface</h1>

<p>
(Getting Started) <a href="start.html">Prev</a>
| <a href="index.html">Index</a> | <a href="options.html">Next</a>
(Setting Options)
</p>
<hr/>

<p>
  Olive does not mimic GUI-style user interfaces by implementing
  text-based menus, controls, and the like. Instead it takes programs
  like <code>mutt</code> as its inspiration and stays out of your way
  as much as possible.
</p>
<p>
  Transient panels and message dialogues aside, the Olive UI is
  composed of 4 components (listed here top-to-bottomly): Title Bar,
  List Pane, Status Line, and Story Pane. Of these four, only the List
  Pane and Story Pane can be interacted with in any meaningful way.
</p>
<p>
  Input focus is shifted between the List Pane and Story Pane with the
  '<code>w</code>' key.
</p>


<h2 id="s10">2.1 The Titlebar</h2>
<p>
  This is Olive's one visual extravagance. The titlebar is simply the
  top line of the window, used to display Olive's name and version
  number in white-on-blue text.
</p>
<pre class='screen'>
  |
  | <span>Olive b7                                                  </span>
  |
</pre>
<p>
  You can hide the titlebar and have this line of screen real-estate
  for your own use. See <a href="options.html#s24">Section 3.2.4</a>
  for details on how to do this.
</p>


<h2 id="s20">2.2 List Pane</h2>
<p>
  The top half of Olive's window is used by the List Pane. This is
  where the stories from the feeds currently in your feed list are
  displayed, one story per line. Each line displays the following
  information:
</p>
<ol>
  <li>Title (taken from RSS data)</li>
  <li>Feed nickname (taken from feed config)</li>
  <li>Age (time since posting, taken from RSS data)</li>
  <li>Read/Unread indicator</li>
</ol>
<p>
  Stories are sorted as follows:
</p>
<ol>
  <li>
    New or Unread stories, sorted oldest-to-newest by age
  </li>
  <li>
    Old stories, sorted newest-to-oldest by age
  </li>
</ol>
<p>
  If there are both new and old stories present in the list, a
  separator line of dashes will be displayed between them.
</p>
<pre class='screen'>
                  TITLE                       FEED         AGE   S U
    |------ (Width - 29 chars) -------| |-- 16 chars --| |- 7 -| 1 1

  | Martian rover rolls free of trap    BBC News         00h 52m   @
  | Pacman comes to life virtually      BBC News         00h 38m * @ 
  | Many dead in Nepalese bus blast     BBC News         00h 12m   @
  | ----------------------------------------------------------------
  | China dismisses US Tiananmen call   BBC News         03h 38m * -
  | Japanese firms raise investment     BBC News         04h 12m   -

</pre>
<p>
  The age field displays '<code>HHh MMm</code>' for stories less than
  one day old, '<code>DDd HHh</code>' for stories between 1 and 100
  days old, '<code>___+99d</code>' for stories 100 or more days old,
  and '<code>____???</code>' for stories with no date (or invalid
  dates) in their RSS data.
</p>
<p>
  The Starred indicator displays '<code>*</code>' for stories you have
  flagged as <em>starred</em> and nothing for stories which are
  unstarred. Starred stories will remain in your story list even after
  they have been removed from the feed they were sourced from. This
  lets you force stories to stick around if you need them for later
  reference. The star flag of a story is toggled with the
  '<code>s</code>' key.
</p>
<p>
  The Read/Unread indicator displays '<code>@</code>' for unread
  stories and '<code>-</code>' for stories which you have already
  read. As you read stories, they will remain in place among the new
  stories until the next feed poll (see 
  <a href="options.html#s30">Section 3.3</a>) occurs; they will then
  be sorted with the old stories. Stories can be marked and unmarked
  as read with the '<code>m</code>' and '<code>u</code>' keys,
  and <em>all</em> stories can be marked/unmarked at once with
  '<code>M</code>' and '<code>U</code>'.
</p>
<p>
  The list cursor is displayed as a bolded reverse-video bar spanning
  the width of the pane.
</p>
<pre class='screen'>
  | Martian rover rolls free of trap    BBC News         00h 52m   @
  | <span class='rv'><b>Pacman comes to life virtually      BBC News         00h 38m * @</b></span> 
  | Many dead in Nepalese bus blast     BBC News         00h 12m   @
  | --------------------------------------------------------------
  | China dismisses US Tiananmen call   BBC News         03h 38m * -
  | Japanese firms raise investment     BBC News         04h 12m   -
</pre>
<p>
  The cursor is moved one line at a time with the up and down arrow
  keys or the '<code>j</code>' and '<code>k</code>' keys, and the
  currently-indicated story is selected with <code>Enter</code>. When
  the cursor is moved from the currently selected story, that story is
  displayed in bold face:
</p>
<pre class='screen'>
  | Martian rover rolls free of trap    BBC News         00h 52m   @
  | <b>Pacman comes to life virtually      BBC News         00h 38m * @</b> 
  | Many dead in Nepalese bus blast     BBC News         00h 12m   @
  | --------------------------------------------------------------
  | <span class='rv'>China dismisses US Tiananmen call   BBC News         03h 38m * -</span>
  | Japanese firms raise investment     BBC News         04h 12m   -
</pre>
<p>
  The cursor movement and story selection functions are combined in
  the '<code>[</code>' and '<code>]</code>' keys, which select the
  previous and next stories in the list,
  respectively. See <a href="options#s22">Section 3.2.2</a> for
  information on how this behavior can be modified.
</p>
<p>
  The cursor can also be moved one "screen" at a time with <code>PgUp</code> and
  <code>PgDn</code>, or to the top and bottom of the list
  with <code>Home</code> and <code>End</code>.
</p>
<p>
  The cursor will return to the top of the list when
  a <a href="feeds.html#s40">feed poll</a> occurs.
</p>
<p>
  The list can be filtered to display only starred stories and/or
  stories belonging to flagged feeds
  (See <a href="feeds.html#s10">Section 4.1</a> for information on
  flagging feeds). Toggle filtering on starred stories with
  '<code>S</code>' and flagged feeds with '<code>F</code>'. The
  current filtering status will be shown in the <a href="#s41">Status
  Area</a> of the Status Line when filtering is active.
</p>
<p>
  The list has search capabilities much like those
  of <code>less</code>. Press '<code>/</code>' to start a search, then
  type your search term and press <code>Enter</code>, which will cause
  the cursor to jump to the first matching line or display <code>Not
  found</code> if there is no match. You can press '<code>n</code>' to
  repeat the search forward or '<code>N</code>' to repeat it
  backwards, <code>Enter</code> to select the current match and end
  the search, or '<code>q</code>' to end the search without selecting
  anything.
</p>






<h2 id="s30">2.3 Story Pane</h2>
<p>
  The bottom half of Olive's window is used by the Story Pane. This is
  where the content of (and some other information from) the currently
  selected story is displayed.
</p>
<pre class='screen'>
  |             Story Title
  |             -----------
  |
  | -- Header
  |
  | Lorem ipsum dolor sit amet, consectetuer 
  | adipiscing elit. Vivamus rhoncus libero. 
  |
  | Aenean sit amet risus sed felis molestie 
  | hendrerit. Pellentesque feugiat mauris.
  |
  | -- 
  | http://someurl/pathto/story.html
</pre>
<p>
  The story text is scrolled one line up or down with the arrow
  keys or the '<code>j</code>' and '<code>k</code>' keys
</p>
<p>
  The story can also be scrolled one "screen" at a time with 
  <code>PgUp</code>/'<code>-</code>'
  and <code>PgDn</code>/<code>SPC</code>, or to the top and bottom
  with <code>Home</code> and <code>End</code>.
</p>
<p>
  The Story Pane is searchable in the same manner as the List Pane.
</p>



<h2 id="s40">2.4 The Status Line</h2>
<p>
  Between the List Pane and the Story Pane sits the Status Line. It is
  a single line which displays various and sundry informational
  mesasges for you. It cannot be turned off, but its behavior can be
  modified.
</p>

<h3 id="s41">2.4.1 The Status Area</h3>
<p>
  Most of the status line is taken up by the Staus Area. If enabled as
  per <a href="options.html#s21">Section 3.2.1</a>, the Status Area
  will display a message in the following format when no other
  activity is happening:
</p>
<pre class='screen'>
  |
  | <span><b>[S: 1/175] [U/N: 21/21] [P: 5 @ 05:45 | 6 since 02:41] [F: F,S]</b>     </span>
  |
</pre>
<p>
  It is read as follows:
<ul>
  <li>
    <code>[S: n/n]</code> &mdash; Stories. The first number is the number
    (in the story list) of the location of the list cursor. The second
    number is the total number of stories in the list.
  </li>
  <li>
    <code>[U/N: n/n]</code> &mdash; Unread/New. The first number is
    how many unread stories remain in the list. The second number is
    now many new stories are currently in the list.
  </li>
  <li>
    <code>[P: n @ HH:MM | n since HH:MM]</code> &mdash; Polling. The
    data on the left side of the pipe is how many feeds were refreshed
    during the last poll, and the time at which that poll
    occurred. The date on the right side is how many
    feeds <b>total</b> have been refreshed since the last user
    activity, which is presently defined for this purpose as "reading
    a story".
  </li>
  <li>
    <code>[F: X,Y,..Z]</code> &mdash; Filtering. The comma-separated
    list of letters indicated which filters are active. <code>F</code>
    for flagged feeds, <code>S</code> for starred stories. If no
    filters are active, this block will not display at all.
  </li>
</ul>
<p>
  When polling is active, the Status Area displays brief messages
  about the polling process (Checking..., Fetching..., etc.) for each
  feed being polled.
</p>
<p>
  When the Story Pane is focused, the Status Area displays the title
  (the actual title, taken from the feed, not the nickname displayed
  in the story list) of the feed from which the currently selected
  story is taken.
</p>

<h3 id="s42">2.4.2 The Focus Pointer</h3>
<p>
  The rightmost character of the Status Line is the Focus Pointer. It
  simply points to whichever of the the List Pane (<code>^</code>) or
  the Story Pane (<code>V</code>) is focused.
</p>

<hr/>
<p>
(Getting Started) <a href="start.html">Prev</a>
| <a href="index.html">Index</a> | <a href="options.html">Next</a>
(Setting Options)
</p>
<hr/>
<p>
$Id: ui.html 322 2005-11-19 07:38:59Z mdxi $
</p>
</body>
</html>
